All Databases Inside Mac - Basic Toolbox

NewCDialog

Create a color dialog using program parameters

#include <Dialogs.h> Dialog Manager

DialogPtr NewCDialog(dStorage, wRect, title, visFlag, wDefProcID, behind,

goAwayFlag, refCon, itemList );

Ptr dStorage ; address of a DialogRecord; NIL=allocate one

Rect *wRect ; bounding rectangle in global coordinates

Str255 title ; text for title line; use "\p" if not needed

Boolean visFlag ; TRUE=draw now; FALSE=suppress

short wDefProcID ; window definition ID

WindowPtr behind ; window plane; -1=in front, else= window

Boolean goAwayFlag ; TRUE=window has a close box

long refCon ; application's reference " constant

Handle itemList ; generic handle to a list of items

returns Address of a DialogRecord

NewCDialog creates a color dialog and returns a DialogPtr for use in

subsequent Dialog Manager functions. The dialog window is created as with

NewCWindow. The GetNewDialog function is used more often since it also

sets up the item list.

dStorage specifies where the DialogRecord should be stored. It is one of:

NIL (0) Storage is allocated as a non-relocatable object on the heap.

This could cause heap fragmentation later. Use DisposDialog

to release the dialog record and related storage areas.

an address (≠0) The DialogRecord will go into the caller- created buffer

starting at dStorage. Use CloseDialog to free up storage for

the window and items. You will be responsible for freeing the

memory used by the DialogRecord itself.

wRect is a pointer to a Rect, in global coordinates, which defines the size

and position of the dialog window. To avoid overwriting the menu

bar, the top field should be at least 25 (modal dialog) or at least 40

(modeless dialog).

title is the address of a length-prefixed string that will be used as the

dialog window's title in its drag region. For a modal (un titled)

dialog, use an empty string (e.g., "\p" ).

visFlag is a Boolean value specifying whether or not the dialog window is to

be made visible immediately. A value of FALSE performs the

necessary memory allocations and other initialization, but

suppresses the actual drawing. You can use ShowWindow, later to

make is visible. Creating a color dialog with this flag set to FALSE is

recommended unless the dialog's content is white. Calls to

ShowWindow are best made after the color table and item list are

installed for frontmost windows. Use ShowHide when you want to

display windows that aren't initially brought up as the frontmost

window.

wDefProcID is the window definition ID that identifies the function darwing the

window. Refer to NewCWindow for a list of standard window types

and their named constants. For dialogs, use:

dBoxProc 1 Standard alert box or modal dialog box

plainDBox 2 Plain old box

altDBoxProc 3 Plain box with shadow

noGrowDocProc 4 For modeless dialogs (has a title)

See Window Types for a graphic display of window types.

behind specifies the dialog window's plane - whether it is in front or

behind other windows on the screen. It is one of:

-1 in front of all other windows

else a valid WindowPtr; new window will go behind this one

goAwayFlag is a Boolean value specifying whether or not the window has a close

box in the top left corner. This should be FALSE for modal dialogs.

refCon is an application-specific reference number. It's value is set and

used only by the application. Since it is a 32-bit value, you can store

a handle or a pointer in here.

itemList is a generic Handle, which leads to a variable-length list of item

information structures (un documented). This is normally a handle

to the data of an 'DITL' resource obtained via GetResource.

Returns: a DialogPtr (the address of a DialogRecord) containing the window

and dialog information. A return value of NIL indicates that the

operation was unsuccessful.

Note: The first fields of a DialogRecord are the same as a

WindowRecord and, in fact the DialogPtr is actually a WindowPtr.

Thus, it may be used anywhere a cGrafPtr or WindowPtr is required

(SetPort, ShowWindow, etc.). To access the unique fields of the

DialogRecord, cast the return value to a DialogPeek.

Notes: NewCDialog is the same as NewDialog except that it works with a

cGrafPort instead of a GrafPort and NewCWindow instead of NewWindow.

First you call NewCDialog, and then you call SetWinColor to give the

dialog its color table by assigning it an auxWinRec. Access to the auxiliary

window record is through the GetAuxWin routine where the dialogCItem

handle points to the dialog item color table.

NewCDialog is similar to NewCWindow in many ways. It creates and

( optionally) draws and activates a window. The first 8 parameters of the

two functions match. The returned DialogPtr is actually a WindowPtr

(which is really a CGrafPtr). To access the additional fields of a

DialogRecord, you can cast the DialogPtr into a DialogPeek:

DialogPtr dlgPtr;

DialogPeek dlgPeek;

dlgPtr= NewCDialog( ... );

dlgPeek = (DialogPeek)dlgPtr;

x = dlgPtr->portRect.top; [TOKEN:12074] access a CGrafPort field */

x = dlgPtr->aDefItem; [TOKEN:12074] ERR: can't get to DialogRecord */

x = dlgPeek->aDefItem; [TOKEN:12074] OK: access a DialogRecord field*/

x = dlgPeek-> window. windowKind; /* or a WindowRecord field */

The itemList parameter is obtained via GetResource('DITL',...). It is

possible to build an item list on the fly and use the handle of that list in this

call. You could also create a 'DITL' resource containing empty items and use

SetDItem to change their contents.

Color Dialog Item Lists

If an 'ictb' resource is present and has the same ID as 'DITL' and if either

a 'dctb' or an 'actb' resource is also present, the statText, editText, and

control items in the dialog and alert boxes are generated in color and in the

style specified by the resource's item color table.

You can see that the item color table's record starts with entries for a double

field that specify the length of a control entry (or for the text style for editText

or statText items) and an offset from the start of the record to the color item

entry.

For editText and statText color item entries, itemCData tells which fields

of the text style record to use, as in:

bit 0= Change font family

bit 1= Change type face

bit 2= Change type size

bit 3= Change font foreground color

bit 4= Add the font size

bit 13= Change font background color

bit 14= Change the font mode

bit 15= The diFont field is an offset to the font's name

When itemCData references a text item, it contains a superset of the flags

passed as the mode word to the TextEdit TESetStyle routine. Those

TextEdit and dialog box constants are:

TEdoFont= 1=  set the font family  number
TEdoFace= 2 = set the character style
TEdoSize= 4 = set the type size
  TEdoColor= 8 = set the foreground  color
TEdoAll= 15 =  set all  attributes
TEaddSize= 16 =  adjust the type size

Additionally, the following constants apply specifically to dialog boxes:

doBColor= 8192 = set the background  color
doMode =  16384 = set txMode
doFontName = 32768 = set txFont from font name

When the itemCOffset field points to the beginning of a text style record, it

leads to a 20-byte block of data that includes the information for Font,

Style, Size, Foreground and Background colors and Mode. The same text

style record can be used by several different statText and editText items at

the same time. Setting both itemCData itemCOffset to zero will display text

in the standard font, color, size and style. You must reserve space for all of

the fields, regardless of whether or not they're all used. Set unused entries

to zero.

When dealing with color controls, the item color table is identical with the

contents of a 'cctb' resource. As with text records, many controls can use

the same color table. If you set the itemCData and itemCOffset fields to zero,

the control will be displayed in the default colors. An entry in the control

color table should be 16 bytes long, i.e., the header (8 bytes) plus the

ColorSpec record for each color table entry (8 bytes). See the Control

Manager for more information.

While the doFontName array is optional, you should point to the name of

the font instead of just including the font number because font installers

can change font numbers. See GetFNum for more information.

Referenced by (6):